---
title: Quick Start
description: Getting Started with Fumadocs
icon: Album
---

import { File, Folder, Files } from 'fumadocs-ui/components/files';
import { CpuIcon, PanelsTopLeft, Database, Terminal } from 'lucide-react';

## Introduction

Fumadocs is a **documentation framework** based on Next.js, designed to be fast and flexible.
It composes seamlessly into Next.js App Router, allowing a high flexibility with code.

Fumadocs has different parts:

<Cards>

<Card icon={<CpuIcon className="text-purple-300" />} title='Fumadocs Core'>

Handles most of the logic, including document search, content source adapters, and Markdown extensions.

</Card>

<Card icon={<PanelsTopLeft className="text-blue-300" />} title='Fumadocs UI'>

The default theme of Fumadocs, it offers a beautiful look for documentation sites and many interactive components.

</Card>

<Card icon={<Database />} title='Content Source'>

The input/source of your content, it can be a CMS, or local data layers like [Content Collections](https://www.content-collections.dev) and [Fumadocs MDX](/docs/mdx), the official content source.

</Card>

<Card icon={<Terminal />} title='Fumadocs CLI'>

A command line tool to configure features automatically, and install UI components (similar to Shadcn UI).

</Card>

</Cards>

### Use Cases

### Documentation

Fumadocs focuses on **authoring experience**, it provides a beautiful theme and many docs automation tools.

It helps you to iterate your codebase faster while never leaving your docs behind.
You can take this site as an example of docs site built with Fumadocs.

### Blog sites

Since Next.js is already a powerful framework, most features can be implemented with **only Next.js**.

Fumadocs can process the content (e.g. syntax highlighting), and you can use the default theme (Fumadocs UI) or your custom theme.
It is particularly helpful if you want to build complicated things like search.

### Terminology

For a better understanding of the docs, there are some common terminologies you should know:

**Page Tree:** A tree of all the pages, separators and folders. It is essential for navigation elements, usually generated by the content source or hardcoded. See [Types definitions](/docs/headless/page-tree).

**Markdown (MDX) File:** A Markdown file could be located in a folder, or available remotely.

Some basic knowledge of Next.js App Router would be useful for further customisations.

## Automatic Installation

Create a new app with `create-fumadocs-app`, it requires Node.js 18+.

<Tabs groupId='package-manager' persist items={['npm', 'pnpm', 'yarn', 'bun']}>

```bash tab="npm"
npm create fumadocs-app
```

```bash tab="pnpm"
pnpm create fumadocs-app
```

```bash tab="yarn"
yarn create fumadocs-app
```

```bash tab="bun"
bun create fumadocs-app
```

</Tabs>

It will ask you the following questions:

- Which content source to use? (Recommended: Fumadocs MDX)
- Configure Tailwind CSS?
- Install dependencies?

After that, it will initialize a new fumadocs app.
Now you can start hacking!

### Enjoy!

Create your first mdx file in the docs folder.

```mdx title="content/docs/index.mdx"
---
title: Hello World
---

## Yo what's up
```

Run the app in development mode and see http://localhost:3000/docs.

```package-install
npm run dev
```

### Explore

In the project, you can see:

- `lib/source.ts`: Where you organize code for content source adapter, we use [`loader`](/docs/headless/source-api) to read from content source.
- `app/layout.config.tsx`: Shared options for layouts, this is optional but preferred to keep.
- `app/(home)`: The route group for your landing page and other pages.
- `app/docs`: The documentation layout and pages.
- `app/api/search/route.ts`: The Route Handler for search.

#### Content Source

Visit the docs of your content source, content source manages the validation and type definitions of content (e.g. frontmatter properties), and transform them to data on JavaScript runtime.

For Fumadocs MDX, see [Introduction](/docs/mdx) for details:

- `source.config.ts`: Config file for Fumadocs MDX.

For other formats and content sources, they can be supported using a custom adapter.
If you use a custom content source (e.g. Notion), you can [build a custom `loader` instead](/docs/headless/remote).

## FAQ

Some common questions you may encounter.

<Accordions>
    <Accordion id='customise' title='How to Customise UI?'>

Fumadocs UI offers Themes, Layouts and Components.

The design system is built with Tailwind CSS, see [Themes](/docs/ui/theme).

Components are pre-built elements to enhance your documentation,
they are customisable with exposed props like `style` and `className`.

Layouts are essential elements of docs, providing navigation and basic functionality.
We provided many options to customise them, see [Layouts](/docs/ui/layouts).

Fumadocs CLI offers a way to install Fumadocs components to your project, allowing you to fully customise them with code.

```package-install
@fumadocs/cli --save-dev
```

```bash
pnpm fumadocs add
```

This is inspired and very similar to Shadcn UI.

    </Accordion>
    <Accordion id='fix-monorepo-styling' title="How to fix stylings not being applied in Monorepo?">

Sometimes, `fumadocs-ui` is not installed in the workspace of your Tailwind CSS configuration file. (e.g. a monorepo setup).

When using the official Tailwind CSS plugin, it will not be able to find the files from `fumadocs-ui` package.

To fix this, edit the Tailwind CSS configuration and replace `./node_modules` with `../../node_modules` in the `content` section.

```js
export default {
  content: [
    './node_modules/fumadocs-ui/dist/**/*.js', // [!code --]
    '../../node_modules/fumadocs-ui/dist/**/*.js', // [!code ++]
    './components/**/*.{ts,tsx}',
    // ...
  ],
};
```

    </Accordion>
    <Accordion id='change-base-url' title="How to change the base route of /docs?">

You can change the base route of docs (e.g. from `/docs/page` to `/info/page`).
Since Fumadocs uses Next.js App Router, you can simply rename the route:

<Files>
  <Folder name="app/docs" defaultOpen className="opacity-50" disabled>
    <File name="layout.tsx" />
  </Folder>
  <Folder name="app/info" defaultOpen>
    <File name="layout.tsx" />
  </Folder>
</Files>

And tell Fumadocs to use the new route in `source.ts`:

```ts title="source.ts"
import { createMDXSource } from 'fumadocs-mdx';
import { loader } from 'fumadocs-core/source';
import { docs, meta } from '@/.source';

export const source = loader({
  baseUrl: '/info',
  source: createMDXSource(docs, meta),
});
```

    </Accordion>
    <Accordion id='dynamic-route' title="It uses Dynamic Route, will it be poor in performance?">

Next.js turns dynamic route into static routes when `generateStaticParams` is configured.
Hence, it is as fast as static pages.

You can enable Static Exports on Next.js to get a static build output. (Notice that Route Handler doesn't work with static export, you have to configure static search)

    </Accordion>
    <Accordion id='pronunciation' title='How to say Fumadocs?'>
        Fumadocs (Foo-ma docs).
    </Accordion>
    <Accordion id='custom-layout-docs-page' title='How to create a page in /docs without docs layout?'>

Same as managing layouts in Next.js App Router, remove the original MDX file from content directory (`/content/docs`).
This ensures duplicated pages will not cause errors.

Now, You can add the page to another route group, which isn't a descendant of docs layout.

For example, under your `app` folder:

<Files>
  <File name="(home)/docs/page.tsx" />
  <Folder name="docs">
    <File name="layout.tsx" />
    <File name="[[...slug]]/page.tsx" />
  </Folder>
</Files>

will replace the `/docs` page with your `page.tsx`.

    </Accordion>

</Accordions>

### Why Fumadocs?

Feel free to open the demo in CodeSandbox and see if it suits you.

- Many built-in components.
- Integrations with Typescript Twoslash, OpenAPI, Math (KaTeX).
- Flexible and Fast by default.
- Built on App Router, no need for hydration over static content.
- Use it in an existing Next.js project, without refactoring anything.

Make sure to read [Comparisons](/docs/ui/comparisons) if you're interested.

## Learn More

New to here? Don't worry, we are welcome for your questions.

If you find anything confusing, please give your feedback on [Github Discussion](https://github.com/fuma-nama/fumadocs/discussions)!

<Cards>
  <Card
    href="/docs/ui/page-conventions"
    title="Organizing Pages"
    description="Learn how to organize your pages"
  />
  <Card
    href="/docs/ui/navigation"
    title="Navigation Links"
    description="Learn how to customise navigation links in Fumadocs"
  />
  <Card
    href="/docs/ui/theme"
    title="Theming"
    description="Add themes to Fumadocs UI"
  />
  <Card
    href="/docs/ui/markdown"
    title="Markdown"
    description="Learn how to write documents in Fumadocs"
  />
</Cards>

### From Existing Codebase?

You can follow the Manual Installation guide to get started.

<Cards>
  <Card
    href="/docs/ui/manual-installation"
    title="Manual Installation"
    description="Create fumadocs app from scratch"
  />
</Cards>
